Add Agentic skills: draft-issue, review-blog-post, review-pull-request by vitorvasc · Pull Request #9626 · open-telemetry/opentelemetry.io

vitorvasc · 2026-04-10T19:54:52Z

Summary

Contributes to #9397.

Introduces 3 agentic skills under .claude/skills/ to assist contributors working on this repo:

draft-issue - draft issues against the real .github/ISSUE_TEMPLATE/ templates
review-blog-post - review blog PRs/drafts for frontmatter, conventions, gh-url-hash, and OTel terminology
review-pull-request - review PRs against CI checks, CLA/approval workflow, refcache, and content conventions

All content introduced in this PR is an initial proposal. Iteration on the scope, prompts, and conventions are expected before merging. Feedback is always welcome :)

Usage

`/review-pull-request`

Arguments:

/review-pull-request <PR number or URL>

Examples:

/review-pull-request 9614
/review-pull-request https://github.com/open-telemetry/opentelemetry.io/pull/9614

`/review-blog-post`

Arguments:

/review-blog-post <blog post path or PR number>

Examples:

/review-blog-post content/en/blog/2026/my-new-post/index.md
/review-blog-post 9580

`/draft-issue`

Arguments:

/draft-issue <description of issue to draft>

Examples:

/draft-issue the Kubernetes getting-started page references a deprecated flag
/draft-issue feature: add a copy-to-clipboard button on code samples
/draft-issue blog: proposal for a post about exemplars in Prometheus

Signed-off-by: Vitor Vasconcellos <[email protected]>

theletterf

Interesting! How are arguments parsed?

vitorvasc · 2026-04-23T12:03:37Z

Interesting! How are arguments parsed?

@theletterf, Claude interprets them semantically, so I haven't been explicitly documenting that in the instructions. It's worked fine so far, but given our recent threads on Slack and @chalin's experience while using Copilot to interpret agent skills, I think it's worth being explicit about the expected arguments.

I'll update the skills to make it clearer. :)

Signed-off-by: Vitor Vasconcellos <[email protected]>

Copilot

Pull request overview

Adds an initial set of contributor-focused “agentic skills” and supporting assets under .claude/ to help draft issues, review PRs/blog posts, and batch-triage GitHub issues for the OpenTelemetry website repo (and optionally other repos), including a triage sub-agent, schemas, and a frontmatter validation hook.

Changes:

Introduces 4 skills: otel-triage, otel-pr-review, otel-issue-draft, otel-blog-review.
Adds an otel-issue-triager sub-agent plus triage profile/state JSON schemas and repo-specific triage profiles.
Adds a .claude PreToolUse hook intended to validate blog frontmatter on Write/Edit operations.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
`.claude/skills/otel-triage/SKILL.md`	Defines the batch issue triage workflow, report/state format, and profile merge behavior.
`.claude/skills/otel-pr-review/SKILL.md`	Documents PR review workflow and CI check semantics for `opentelemetry.io`.
`.claude/skills/otel-issue-draft/SKILL.md`	Guides drafting issues aligned to repo templates and label taxonomy.
`.claude/skills/otel-blog-review/SKILL.md`	Documents blog post review rules (frontmatter, `gh-url-hash`, terminology, etc.).
`.claude/agents/otel-issue-triager.md`	Sub-agent spec for per-issue deep triage analysis and dossier generation.
`.claude/schemas/triage-state.schema.json`	JSON schema for triage run state tracking.
`.claude/schemas/triage-profiles.schema.json`	JSON schema for triage profiles (repo config + evaluation criteria).
`.claude/data/opentelemetry-website.yml`	Repo profile for `open-telemetry/opentelemetry.io` (keywords, taxonomy, templates).
`.claude/data/bloomberg-mentorship.yml`	Evaluation profile for Bloomberg mentorship suitability.
`.claude/hooks/hooks.json`	Registers a pre-tool hook for Write/Edit actions.
`.claude/hooks/frontmatter-check.sh`	Hook script to validate blog post frontmatter and heading rules.

Copilot · 2026-04-23T12:24:32Z

+# Check for H1 headings in content (after frontmatter)
+BODY=$(echo "$CONTENT" | awk 'BEGIN{n=0} /^---$/{n++; next} n>=2{print}')
+if echo "$BODY" | grep -qE '^# [^#]'; then


The H1 check scans the entire body with a simple grep '^# ', which will also match shell comments or other lines inside fenced code blocks (common in blog posts), causing false failures. Consider tracking fenced-code state (``` / ~~~) and only flagging # headings outside code fences, or using a markdown-aware parser.

Suggested change

# Check for H1 headings in content (after frontmatter)

BODY=$(echo "$CONTENT" | awk 'BEGIN{n=0} /^---$/{n++; next} n>=2{print}')

if echo "$BODY" | grep -qE '^# [^#]'; then

# Check for H1 headings in content (after frontmatter), ignoring fenced code blocks

BODY=$(echo "$CONTENT" | awk 'BEGIN{n=0} /^---$/{n++; next} n>=2{print}')

if echo "$BODY" | awk '

BEGIN {

in_fence = 0

fence_char = ""

}

/^[[:space:]]*```/ {

if (!in_fence) {

in_fence = 1

fence_char = "`"

next

}

if (fence_char == "`") {

in_fence = 0

fence_char = ""

next

}

}

/^[[:space:]]*~~~/ {

if (!in_fence) {

in_fence = 1

fence_char = "~"

next

}

if (fence_char == "~") {

in_fence = 0

fence_char = ""

next

}

}

!in_fence && /^# [^#]/ {

found = 1

exit

}

END {

exit found ? 0 : 1

}

'; then

linux-foundation-easycla · 2026-04-23T12:30:19Z

The committers listed above are authorized under a signed CLA.

✅ login: otelbot[bot] / name: otelbot (b07f64c, fc2d197)
✅ login: vitorvasc / name: Vitor Vasconcellos (0195f15, 0ab1e1d, 495920f, 8342181, 15de35e, 1bce79b, 2262678, 26800c7, 28b0e8b, 2eae4e7, 36cfce0, 3ce688a, 3d6c8fa, 3eab61e, 49f1ec3, 4ac1d03, 4ec2f17, 5d2b59a, 6e7dc34, 73a8ed7, 756422a, 7628ae3, 7a5af3a, 7b92013, 7de665b, 8480fbd, 89a0ae3, 8e43588, 94b5733, 9540d6b, 984b474, 9dab0fb, a447d96, b8fcbdc, bceb1b3, bcecd90, c07ba12, d4f1337, d8cd6a3, e4c2b71, e6bfe03, eb7f3cd, f51b3a1, f614530)

Signed-off-by: Vitor Vasconcellos <[email protected]>

…skill references Signed-off-by: Vitor Vasconcellos <[email protected]>

Signed-off-by: Vitor Vasconcellos <[email protected]>

…dict categories Signed-off-by: Vitor Vasconcellos <[email protected]>

…te instructions for labels Signed-off-by: Vitor Vasconcellos <[email protected]>

…om the triage-issue/references skill Signed-off-by: Vitor Vasconcellos <[email protected]>

Signed-off-by: Vitor Vasconcellos <[email protected]>

vitorvasc · 2026-04-28T18:01:14Z

/fix:format

otelbot-docs · 2026-04-28T18:07:19Z

✅ fix:format applied successfully in run 25069384208.

…skill Signed-off-by: Vitor Vasconcellos <[email protected]>

Signed-off-by: Vitor Vasconcellos <[email protected]>

Removes the triage-issue skill and its supporting infrastructure (subagent, profile/state schemas, repo and Bloomberg-mentorship profiles) so this PR focuses on the website-specific skills: draft-issue, review-blog-post, and review-pull-request. The triage subsystem is generic (works on any repo via --repo) and addresses scope/DRY concerns raised in review. The deferred work is preserved on a local site_agentic-skills_triage branch. Signed-off-by: Vitor Vasconcellos <[email protected]>

…pstream Replaces the inline label taxonomy with a pointer to `gh label list`, `.github/component-label-map.yml`, and `sig-practices.md`. Replaces the five inline issue-template body structures with a one-line directive to mirror the real `.github/ISSUE_TEMPLATE/*.yml` section labels verbatim. Single source of truth, fewer drift risks, ~half the lines. Signed-off-by: Vitor Vasconcellos <[email protected]>

Drops front matter rules already enforced by the front-matter-check hook, prettier, markdownlint (gh-url-hash), and cSpell — keeps only the judgment layer those tools cannot check (multi-author folded form, sentence vs title case, optional field semantics, OTel terminology, publish-timing gating, cross-posting). Compresses the 72-line review checklist into a tight 7-item walkthrough that complements the body. From 377 to ~180 lines. Signed-off-by: Vitor Vasconcellos <[email protected]>

…ta pointer Inlines the 72-line references/content-review.md into the workflow steps and final-pass checklist (single SKILL.md, no references/ subfolder). Drops the bullet pointing at the now-deleted .claude/data/opentelemetry-website.yml. Consolidates the two trailing References sections into one, and the duplicate "Bundled references"/"References" headers into a single source-of-truth list. Signed-off-by: Vitor Vasconcellos <[email protected]>

Signed-off-by: Vitor Vasconcellos <[email protected]>

chalin

TY @vitorvasc! ✨
Let's give this a spin, and incrementally improve. I think you've removed the triage skill (if so update the opening comment). Looking forward to seeing that land as well in a followup PR, if that's what you choose.

vitorvasc · 2026-04-30T10:10:37Z

@chalin - that's correct! Just updated the title and description, and I'll raise the follow-up PR for the triaging skill as soon as I get back to it. :)

Let me know if you run into any issues with the skills in this PR.

open-telemetry#9626) Signed-off-by: Vitor Vasconcellos <[email protected]> Co-authored-by: otelbot <[email protected]>

vitorvasc added 4 commits April 10, 2026 14:26

feat: add review skill for blog posts

8e43588

Signed-off-by: Vitor Vasconcellos <[email protected]>

feat: add otel-issue-draft skill

5d2b59a

Signed-off-by: Vitor Vasconcellos <[email protected]>

feat: add otel-pr-review skill

49f1ec3

Signed-off-by: Vitor Vasconcellos <[email protected]>

feat: add otel-triage skill

3ce688a

Signed-off-by: Vitor Vasconcellos <[email protected]>

github-project-automation Bot added this to SIG Comms: PRs & Issues Apr 10, 2026

otelbot-docs Bot added the missing:docs-approval Co-owning SIG has provided approval, PR needs approval from docs maintainer label Apr 10, 2026

vitorvasc added 2 commits April 10, 2026 17:12

remove 'contributor' folder, fix format

3eab61e

Signed-off-by: Vitor Vasconcellos <[email protected]>

add Bloomberg OSS mentorship evaluation criteria

4ac1d03

Signed-off-by: Vitor Vasconcellos <[email protected]>

theletterf reviewed Apr 13, 2026

View reviewed changes

Merge branch 'main' into site_agentic-skills

0195f15

vitorvasc and others added 2 commits April 23, 2026 09:17

chore(skills): enhance argument handling

984b474

Signed-off-by: Vitor Vasconcellos <[email protected]>

Merge branch 'main' into site_agentic-skills

495920f

vitorvasc marked this pull request as ready for review April 23, 2026 12:17

vitorvasc requested a review from a team as a code owner April 23, 2026 12:17

Copilot AI review requested due to automatic review settings April 23, 2026 12:17

Copilot started reviewing on behalf of vitorvasc April 23, 2026 12:17 View session

Copilot AI reviewed Apr 23, 2026

View reviewed changes

vitorvasc added 6 commits April 23, 2026 10:04

chore: rename review-blog-post skill

b8fcbdc

Signed-off-by: Vitor Vasconcellos <[email protected]>

chore: rename draft-issue skill

15de35e

Signed-off-by: Vitor Vasconcellos <[email protected]>

chore: rename review-pull-request skill

756422a

Signed-off-by: Vitor Vasconcellos <[email protected]>

chore: rename triage-issue skill

6e7dc34

Signed-off-by: Vitor Vasconcellos <[email protected]>

chore: add Polish language support to repo configuration

1bce79b

Signed-off-by: Vitor Vasconcellos <[email protected]>

chore: address code review suggestions

d8cd6a3

Signed-off-by: Vitor Vasconcellos <[email protected]>

vitorvasc force-pushed the site_agentic-skills branch from 730820e to d8cd6a3 Compare April 23, 2026 13:04

vitorvasc and others added 3 commits April 23, 2026 10:05

Merge branch 'main' into site_agentic-skills

8342181

chore: improve error handling in frontmatter-check script and update …

8480fbd

…skill references Signed-off-by: Vitor Vasconcellos <[email protected]>

fix refcache

f51b3a1

Signed-off-by: Vitor Vasconcellos <[email protected]>

vitorvasc changed the title ~~[WIP] Agentic skills: contributor~~ Add Agentic skills: draft-issue, review-blog-post, review-pull-request, triage-issue Apr 23, 2026

vitorvasc added 6 commits April 28, 2026 12:17

fix(triage-issue): update command block omission rule and add new ver…

bcecd90

…dict categories Signed-off-by: Vitor Vasconcellos <[email protected]>

fix(label-taxonomy): update and expand label taxonomy; remove duplica…

89a0ae3

…te instructions for labels Signed-off-by: Vitor Vasconcellos <[email protected]>

chore: refactor otel-issue-triager agent, add instructions to read fr…

e4c2b71

…om the triage-issue/references skill Signed-off-by: Vitor Vasconcellos <[email protected]>

fix(otel-issue-triager): update agent name to match naming conventions

28b0e8b

Signed-off-by: Vitor Vasconcellos <[email protected]>

chore: add comment to clarify path traversal in hook configuration

2262678

Signed-off-by: Vitor Vasconcellos <[email protected]>

chore: clarify source of truth for label taxonomy and usage instructions

bceb1b3

Signed-off-by: Vitor Vasconcellos <[email protected]>

vitorvasc force-pushed the site_agentic-skills branch from 6944f6d to 6b7265f Compare April 28, 2026 18:15

vitorvasc added 9 commits April 28, 2026 16:08

chore: clean up and reorganize documentation for review-pull-request …

7de665b

…skill Signed-off-by: Vitor Vasconcellos <[email protected]>

chore(review-pull-request): update step references in documentation

9dab0fb

Signed-off-by: Vitor Vasconcellos <[email protected]>

chore(review-pull-request): remove redundant external references

4ec2f17

Signed-off-by: Vitor Vasconcellos <[email protected]>

chore(refcache): drop entry for removed triage-issue skill page

73a8ed7

Signed-off-by: Vitor Vasconcellos <[email protected]>

chore: apply prettier formatting to trimmed skills

94b5733

Signed-off-by: Vitor Vasconcellos <[email protected]>

vitorvasc force-pushed the site_agentic-skills branch from 2344bf6 to 94b5733 Compare April 28, 2026 19:09

Merge branch 'main' into site_agentic-skills

0ab1e1d

chalin approved these changes Apr 29, 2026

View reviewed changes

otelbot-docs Bot removed the missing:docs-approval Co-owning SIG has provided approval, PR needs approval from docs maintainer label Apr 29, 2026

vitorvasc changed the title ~~Add Agentic skills: draft-issue, review-blog-post, review-pull-request, triage-issue~~ Add Agentic skills: draft-issue, review-blog-post, review-pull-request Apr 30, 2026

vitorvasc added this pull request to the merge queue Apr 30, 2026

Merged via the queue into open-telemetry:main with commit 805e163 Apr 30, 2026
25 checks passed

vitorvasc deleted the site_agentic-skills branch April 30, 2026 10:16

github-project-automation Bot moved this to Done in SIG Comms: PRs & Issues Apr 30, 2026

-# Check for H1 headings in content (after frontmatter)
-BODY=$(echo "$CONTENT" | awk 'BEGIN{n=0} /^---$/{n++; next} n>=2{print}')
-if echo "$BODY" | grep -qE '^# [^#]'; then
+# Check for H1 headings in content (after frontmatter), ignoring fenced code blocks
+BODY=$(echo "$CONTENT" | awk 'BEGIN{n=0} /^---$/{n++; next} n>=2{print}')
+if echo "$BODY" | awk '
+  BEGIN {
+    in_fence = 0
+    fence_char = ""
+  }
+  /^[[:space:]]*```/ {
+    if (!in_fence) {
+      in_fence = 1
+      fence_char = "`"
+      next
+    }
+    if (fence_char == "`") {
+      in_fence = 0
+      fence_char = ""
+      next
+    }
+  }
+  /^[[:space:]]*~~~/ {
+    if (!in_fence) {
+      in_fence = 1
+      fence_char = "~"
+      next
+    }
+    if (fence_char == "~") {
+      in_fence = 0
+      fence_char = ""
+      next
+    }
+  }
+  !in_fence && /^# [^#]/ {
+    found = 1
+    exit
+  }
+  END {
+    exit found ? 0 : 1
+  }
+'; then

Conversation

vitorvasc commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Usage

/review-pull-request

/review-blog-post

/draft-issue

Uh oh!

theletterf left a comment

Choose a reason for hiding this comment

Uh oh!

vitorvasc commented Apr 23, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

linux-foundation-easycla Bot commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vitorvasc commented Apr 28, 2026

Uh oh!

otelbot-docs Bot commented Apr 28, 2026

Uh oh!

chalin left a comment

Choose a reason for hiding this comment

Uh oh!

vitorvasc commented Apr 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vitorvasc commented Apr 10, 2026 •

edited

Loading

`/review-pull-request`

`/review-blog-post`

`/draft-issue`

linux-foundation-easycla Bot commented Apr 23, 2026 •

edited

Loading